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IMPORTANT! 


DUPLICATE 
THIS 
DISKETTE 
BEFORE 
USING 
THIS PROGRAM! 


This APX diskette is unnotched to protect the software against accidental erasure. 
However, this protection also prevents a program from storing information on the 
diskette. The program you’ve purchased involves storing information. Therefore, 
before you can use the program, you must duplicate the contents of the diskette onto 
a notched diskette that doesn’t have a write-protect tab covering the notch. 


To duplicate the diskette, call the Disk Operating System (DOS) menu and select 
option J, Duplicate Disk. You can use this option with a single disk drive by manually 
swapping source (the APX diskette) and destination (a notched diskette) until the 
duplication process is complete. You can also use this option with multiple disk drive 
systems by inserting source and destination diskettes in two separate drives and 
letting the duplication process proceed automatically. (Note. This option copies 
sector by sector. Therefore, when the duplication is complete, any files previously 
stored on the destination diskette will have been destroyed.) 


Introduction 


The art of creative program debugging 


In the simplest terms, a computer program is a sequence of operations that cause the 
computer to do something. Programming is the task of preparing instructions for the 
computer to execute. That seems simple enough, yet programming maintains an aura 
of mystery about it, so that even the most experienced programmer approaches 
programming with deference and hesitation. Try to get a programmer to commit to 
when a program will be ready, and you'll see what | mean. Even harder is getting a 
programmer to keep the few commitments made, because experience has burned 
many a programmer who promised the world but delivered the Bronx. Dunion’s First 
Law is that things are never as simple as you think they’re going to be. In programming 
this means programs invariably take longer to program than they should—to get them 
working, anyway. What's so difficult about programming computers? The answer is 
mainly that as humans, we aren’t used to thinking as precisely as one has to in 
programming computers. Even the most rational human finds his thought processes 
tempered by emotion, intuition, and insight; the resulting melange comprises more 
than any strictly rational, logical (linear if you will) sequence. Unfortunately, 
computers don’t work that way (yet); they must be instructed in precise terms. And 
with machines that carry out some half million instructions every second, you don't 
have to be too far wrong in a program before disaster strikes. By the time you notice 
something is wrong, it has already happened. The problem is going from the 
conceptual to the concrete, from taking an idea and turning it into a program. 


Who hasn't thought of the better software mousetrap? But it’s easier thinking up ideas 
than it is programming them. It doesn’t have to be that way. As any Craftsman will tell 
you, much of the problem lies in not having the right tools. Programming as a human 
enterprise is somewhere between an art and a science, and no one is sure exactly 
where the tine is drawn. Programming is hindered by inadequate software tools, but 
much of the problem is the attitude and approach towards the act of programming 
itself. | consider myself to be as much an artist as a technician; each new program isa 
new work of art. Not only does the program have to work correctly, but it also has to 
look right and feel right. The computer is an instrument of imagination, a paint brush 
beyond comparison, a pencil filled with millions of untold tales—the ultimate 
instrument, waiting for the performer to bring it to life. | call this attitude the art of 
creative computer programming. 


Muchas | hate to admit it, mistakes work their way into my programs, particulary if !’m 
trying something new—working with a real-time system, perhaps, with color graphics 
and sound. A system like the ATARI Computer is a good example. To reach the full 
potential of this system, we sometimes have to use assembly language programming. 
At this level, every mistake is magnified a thousandfold, and finding those mistakes is 
tough. It could be a syntax error, asemantic error, a timing error, ahardware error, an 
alpha ray zap, ..., the list goes on and on. As Piet Hein said in one of his Grooks, 
“Problems worthy of attack, prove their worth by hitting back”. What we need is 
something that can let us do a better job of debugging, some creative debugging. 
What we need is something like — Dunion’s Debugging Tool. 
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Required accessories 
e 16K RAM 
e ATARI 810 Disk Drive 
e ATARI MACRO Assembler and Program-Text Editor™ (CX8121) 


Optional accessories 


e ATARI BASIC Language Cartridge (for examples) 


Contacting the author 
Users wishing to contact the author may write to him at: 
1196 Borregas 


P.O. Box 427 
Sunnyvale, CA 94086 


2. Introduction 


DDT user’s guide 


DDT ss design philosophy 


The features of the ATARI Computer set it apart from other current personal 
computers. Unfortunately, trying to get to these features from high-level languages 
like BASIC or PILOT is frustrating. In many instances, the only answer is to write at 
least a portion of the program in assembly language. That still wouldn’t be too bad if 
we had decent assembly language development tools, but until very recently we 
didn’t. That situation changed with the release of the ATARI MACRO Assembler, a 
very powerful programming tool. However, considering that assembly language 
programs are wont to be bug-ridden at first (i.e., full of programming mistakes), the 
MACRO Assembler emphasizes a serious need. Namely, what do we do about 
debugging assembly language programs? The ideal solution, of course, would be to 
have access to something like a logic analyzer or other type of hardware development 
system. Most of us don’t, however. So what to do? The answer seemed to be to 
develop a debugging tool specifically designed for use with the MACRO Assembler. 
Thus was born Dunion’s Debugging Tool (DDT). 


DDT is a flexible, extensible, source language debugging tool. That means you 
generally assemble DDT along with your source code as a sort of parasite. You can 
attach DDT to whatever is running inside the ATARI] Home Computer. These 
attachments or “hooks” let DDT coexist with your test program. This flexibility is 
useful in a couple of ways. First, it lets you decide where DDT should reside in 
memory, which may vary, depending on exactly what is being debugged. Second, it 
lets you use the assembler to set up several of DDT’s features. Note, however, that 
DDT is flexible enough that you don’t have to assemble it with your program each 
time. The examples included on the DDT diskette will give you an idea of some ways to 
set up DDT (i.e., attach DDT to a program). 

Most program bugs arise from assumptions (either explicit or implicit) that prove not 
to be true. If this is the case, a debugging too! that forces you to ask to see various 
locations, registers, breakpoints, and so on, misses a crucial point. Many times you 
have no idea at first what is causing a problem. The central idea in DDT is to place as 
much information as possible on the screen and then let your visual pattern 
recognition system (i.e., your eyes and right side of the brain) go to work. In short, let 
the computer do what it does best and let human programmers do what they do best. 


A consequence of this approach is that DDT centers around control of its display 
screen. This control is coupled with the ability to change and monitor the internal state 
of the machine easily so that you can get a much clearer picture of exactly what’s 
going on inside the system at any instant. Most of the time, correcting a program bug 
is easy; finding it is the trick. That’s where DDT comes in. 


The next section describes each of DDT’s features. Following that is a section 
explaining how to get started using DDT and describing the examples. Finally a 
technical appendix contains more information on how some of DDT’s features are 
implemented. Skim the entire manual to get an overview of DDT, and then go back and 
read each section more carefully. Finally, before you begin experimenting, take a 
blank diskette, format it, and write new DOS files on it. Then copy the source or object 
code modules you're interested in. If you want to experiment with one of the object 
code modules, rename it as AUTORUN.SYS. Then all you have to do is turn the 
machine off and back on to load and initialize the code automatically. 
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The DDT screen display 


DDTss screen display shows you the internal state of the machine. The screen is 
divided into several display areas, each of which shows a different aspect of what’s 
going on inside the computer at that instant. 


The display areas are called : 
Register display - a display of the current contents of 6502 registers 
Display window - a window into memory 
Stack display - a display of the top 15 items on the system stack 
Minisymbol table - a table of names and values of current symbols 
Breakpoint table - a table of the settings of breakpoint registers 
Command window - a window showing keyboard commands entered 


The following sections describe each display area. Figure 1 is an example of a typical 
DDT display screen. 


1E2F 20 81 
1E30 75 

1E31 20 

1E32 00 PLA 

1E33. AA TAX 

1E34 68 PLA 

1E35 A8& TAY 

1E36 68 PLA . 
1E37 40 RTI 

1E38 4C JMP LABEL I 

1E39 BE 


1E3A_ FF 

1E3B A9 LDA #53 
1E3C 53 

1E3D__ 30 BMI 2 _1E41 


Figure 1 Typical Screen Display 
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Register display 


Display window 


The lower part of the display screen displays the current contents of the 6502 
processor registers. Whenever you enter DDT, the contents of its registers are copied 
into register shadows, which are then displayed. These shadows are used to restore 
the 6502 registers before control is released back to the program being tested. 


These registers have their contents shown in hexadecimai notation: 


PC =Program counter, a two-byte value 
ACC = Accumulator 

x = X index register 

Y = Y index register 

SP =Stack pointer 


The Processor status register (NV BDI ZC) is shown in binary form, where 


Negative flag 
Overflow flag 

BRK instruction flag 
= Decimal mode flag 

= Interrupt disable flag 
= Zero flag 

= Carry bit 


Wout Wl 


ONT™OU<Z 


The display window forms a window into the system memory address space. This 
window is in the upper left-hand portion of the display screen, and occupies more 
than a quarter of the screen. The window is set upon entry to DDT, or may be moved 
by single stepping, and by either the “E”, the up-arrow, or the down-arrow command. 


The window can be thought of as having one of three possible filters in front of it. You 
can change these filters by using the “W” command (see “The command interpreter” 
section). The first filter, which is set upon initial entry to DDT, is an opaque filter. It has 
a summary of operating instructions written on it. With this filter in place, many 
commands will appear to do nothing. 


The second filter is a disassembly filter. A “greater than” sign ( > ) points to what is 
called the current position. When you enter DDT, this will correspond to the value in 
the PC. The current position may be modified by the “E”, up-arrow, or down-arrow 
command. 


The third filter is a hexadecimal filter. The window shows the hexadecimal value and 
ATASCII representation of up to 48 memory locations. Again, the “ > ” sign indicates 
the current position. 


There are always three bytes, in hexadecimal form, shown above the current position. 
In the disassembly display, each line from the current position down is shown ina 
similar format: first the hexadecimal address of a location, then its contents, and thena 


disassembly readout. Standard 6502 mnemonics are used, with conventional address 
mode indications. 
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Stack display 
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Several features aid debugging. A mnemonic shown in inverse video indicates that a 
breakpoint has been set at that location. In fact, tf you look at the actual contents of 
that location, it will be a0. A BRK instruction in inverse video means that particular 
BRK instruction was not placed there by DDT. This would occur, for instance, in 
looking at memory that is all zeros. 


Second, if the instruction is one of the branch instructions, an up-arrow or down- 
arrow is added to the disassembly display to indicate the direction of the conditional 
branch. The computed address of the conditional branch location also displays. 


Finally, if the address portion of an instruction contains an address defined in the 
minisymbol table, the symbol name will display rather than the hexadecimal value. 
You can use the symbol feature to locate references to asymbol in the code, or simply 
as labels to make the disassembly listing more readable. If the hexadecimal filter is in 
place, each line after the current position line will start on an even four-byte boundary. 
This means the current position line can have from one to four values on it. The 
current position line values are always left justified. 


The middle portion of the upper display screen shows the top locations in the system 
stack. If the stack pointer is set at $E0 or higher (i.e., the stack has less than 15 entries), 
then only those values currently in the stack will display. The display is a top down 
representation. If more than 15 entries are in the stack, then only the top 15 display. 


Examples 
SP=SFF SP=SFE SP=SFD B9 | SP=SFO 
A8 


” 


Minisymbol table 


The upper right-hand portion of the screen contains a minisymbol tabie with room for 
15 variables. This feature lets you monitor the contents of selected variables without 
worrying about where they physically reside. Two-byte values display in high-low 
order (even though they’re generally stored in low-high order). The symbol table is 
located three bytes past the beginning of the DDT code. The first three bytes are a 
JMP DDT ENTRY instruction. The minisymbol table has 135 locations reserved for it. 
Each symbol in the table is in the following form: 


NAME LOCATION BYTES to SHOW 
6 characters for symbol address lor2 
symbol name 2 bytes 1 byte 


An example of setting up a minisymbol table using the ATARI MACRO Assembler 
(AMAC) is the following: 


ORG DDT ; This sets AMAC positon to start of symbol 
; table 

DB ‘VARI ‘ ; Exactly 6 characters please! 

DW VARI ; Let the assembler figure out what value 
; to put here, 

DB 1 ;either a 1 or a 2 to indicate that the 


; variable should be shown as a single-byte 
; or double-byte value. 


You can also use the minisymbol table to keep an eye on standard system variables: 


DB ‘COLPF2’ 
DW 710 
DB 1 


You can monitor a small area of memory by setting up several dummy variables, each 
pointing to one or two successive bytes of memory. 


The minisymbol table has other serendipitous uses. For example, you can define a 
program label as asymbol. The value shown will be meaningless, but the disassembly 
listing in the display window will be more readable: 


DB “LOOP 1 ’ 
DW :LOOP I 
DB. 1 
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Breakpoint table 


Indeed, you can even define a symbol as “——-——-—— or some such form to 
separate different usage areas of the symbol table. Finally, you can use the minisymbol 
table to help locate a portion of your code. To do this you need to set up a dummy 
storage location: 


LCODE DW :CODE 


You would then define the symbol variable in the table as: 


DB ‘LCODE ’ 
DW LCODE 
DB 2 


The value displayed will then be the address of the :CODE module. 


You need not define any more symbols than you want to use. Examine some of the 
example programs to get a better idea of how to use the minisymbol table in various 
ways. Note that your definitions should be the last thing included in the shell program. 
This is to make sure the symbol definitions occur after DDT, which initially sets up the 
table as follows : 


ORG :SSYMT 
ECHO 15 

DB * : 
DW O 

DB 1 

ENDM 


The breakpoint table is located just above the register display. There are six user- 
definable breakpoints and two trap breakpoints, each of which will be shown with its 
current setting. If a register is clear, i.e., not set, then the value shown will be 0000. Ifa 
breakpoint register is set, the value in that register will be the location of where in 
memory a BRK instruction has been placed. However, in the case of the trap 
breakpoints, no BRK instruction is used. These values are used in interpretive mode to 
create the equivalent of a break instruction. 


Command window 


Trap 
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The extreme right-hand part of the bottom of the screen is devoted to the command 
window, the area showing the commands you type in. 


The trap breakpoints are reserved for interpretive mode. In this mode, breakpoints in 
memory are ignored, since DDT already has control of the system. Instead DDT 
checks the values in the TRAP registers. If either equals the address of the next 
instruction to be executed, DDT will halt the interpretive mode. This allows you to 
place pseudo breakpoints in ROM locations, for instance. Then it becomes much 
easier and quicker to reach a certain spot in the ROM code by setting a trap, and 
running in interpretive mode than by single-stepping up to the desired location. 


» 


Breakpoints 


One of the most common debugging techniques is to use what is known as a 
breakpoint. Suppose you’re trying to debug a program that is clobbering the system. 
One of the first things you can do is look at your source code and say, | wonder if it ever 
makes it this far. You then place a “breakpoint” or literally a BRK instruction that will call 
DDT. Thus, when you run your program you will find out one of two things. If your 
code hits the breakpoint and calls DDT, then the problem is beyond that point. 
However, if the program bombs and it never makes it to the breakpoint, you know the 
probiem is prior to that point. You have now begun localizing the bug. Repeating this 
process can eventually locate where in your code the problem resides. 


The breakpoint mechanism is the most common way for you to transfer control to 
DDT. When a program is running, executing a BRK instruction calls DDT, provided 
DDT has been initialized. This causes the DDT screen display to activate, and also 
turns on the keyboard and the function key command interpreter. The breakpoint 
remains set even after it has been encountered in code execution. 


After a breakpoint has been encountered, and control transfers to DDT, there are 
several ways to leave DDT. Using the “C” command sets a breakpoint at the current 
location and then continues code execution. Pressing the START key simply 
continues code execution. The “G” command transfers control to another location. 


You can set up to six breakpoints at a time. The location of the breakpoints is shown in 
the breakpoint register display. If a breakpoint is clear (i.e., not set), it displays as 0000. 
Setting a breakpoint register to a new location automatically restores an existing 
breakpoint, if one is already set for that register. Note also that the “C” command uses 
an internal system breakpoint 0. If any breakpoint (including the “C” breakpoint itself) 
is encountered and control passes to DDT, then the internal “C” breakpoint is cleared. 


Function key controls 


START 


SELECT 


OPTION 


DDT uses the START, SELECT, and OPTION keys for special effects. 


Use this key to continue code execution at the location indicated by the PC register. 
All 6502 registers are updated with the current displayed contents before control is 
transferred. 


Use the SELECT key to toggle back and forth between the DDT screen and whatever 
screen dynamics were active before DDT was called. An attempt has been made to 
allow most alternative features, such as mixed display lists, VBLANK routines, 
alternate character sets, display list interrupts, playfield size changes, and player- 
missiles. 


Use this key to single step the processor. This causes the disassembly filter to be 
turned on, but will not automatically toggle the display screen. See the section of the 
appendix titled “Single stepping” for more information. 
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The command interpreter 


The command interpreter lets you issue keyboard commands to DDT. The command 
window is in the lower right-hand portion of the display screen. The left-hand part of 
this display shows the register state of the machine. 


Each command is a single keystroke. However, depending on the command, 
additional arguments might be required. If the key typed is not a valid DDT command, 
DDT ignores it.The DDT keyboard commands are as follows: 


E <addr> ............ - Examine address addr 

GC. iets ec - Continue, and leave breakpoint 
G <addr> ............ - Go to address addr 

B <1-6>,<addr>....... - Breakpoint 1-6 to location addr 


R <PC,A,P,X.Y,S>,<val> - Register selected is loaded with val 


D <hstring> ......... - Deposit hex string 

Voayen Se cai ss Cae - Pull display window down 
BF sacs Oates Mba tessnasnicice S - Push display window up 

Ti daece weds tatate we ereeeta nace eX - Interpretive mode 

Wo sei eGR Bh aed ae - Window filter toggle 

T <1-2>,<addr> ..... - Trap at address 

S <hstring> .......... - Search for hex string 


These commands are described in the following pages. 


Entering a value 


Several of the keyboard commands require that you enter one or two values. 
Terminate a value entry by typing a delimiter—either a space, acomma, ora RETURN. 
When two values are needed, as with the Breakpoint command, a comma displays 
after you type the first delimiter, regardless of which delimiter you typed. Typing a 
delimiter without entering a value results in DDTs ignoring the entire command 
(exceptions—see the Breakpoint and the Trap Commands). 


The explanations that follow use these abbreviations: 


<addr> = an address value, up to 4 hexadecimal digits 
(sorry, HEX only) 
<1-6> = eithera1,2,3,4,50re6e 
<PC,A,P,X,Y,S>= either PC, A, P, X, YorS 
<byte> = asingle-byte value, up to 2 hexadecimal digits 
<val> = avalue, which can be a byte value or an 
address value, depending on the register chosen 
<hstring> = ahex String up to 10 characters (i.e. 5 hex 


digits) 


The command interpreter (Cl) ignores keys other than 0-9 and A-F for value inputs. 
Use the DELETE key to erase a character. 


Each time DDT expects a value, the Cl sets up a field size corresponding to the 
maximum number of hex digits you should enter (e.g., 4 digits for an address value). 
When you reach this number, DDT allows no additional digits. You can, however, 
delete characters, and then enter new characters. Deleting past the starting point of 
the value field results in DDTs erasing the entire command. 
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Examine E < addr > 


Continue C 


Go G <addr> 


Use the Examine command to set the display window to view an area of memory. The 
extreme left-hand edge of the display window has a “greater than” sign (>) in the 
fourth row, pointing to the current position that was entered as the address in the “E” 
command. Note that the “E” command does not change the state of the display window 
filter, nor does it affect which instruction will be executed next by a single step 
command. 


Use the Continue command to return to the code that cailed DDT and continue 
execution. It functions similarly to the operation of the START key in that execution 
continues at the address indicated by the PC register. However, “C” also leaves an 
additional “system” breakpoint behind. Internally, this is accomplished by single 
stepping past the instruction, and then setting an internal, invisible breakpoint register 
to the location just left. Only one internal breakpoint can be maintained. If one has 
already been set, it will first be restored before setting the new one. This breakpoint 
will be cleared whenever any breakpoint (including the C breakpoint itself) is 
encountered during code execution. 


Use the Go command to begin execution at a specific location in memory. Before 
control passes to this location, all registers are updated based upon the current 
contents of the displayed registers. This is true for all commands involving code 
execution. 


Breakpoint B <1-6> , <addr> 


Use the Break point command to set one of the six breakpoint registers to a location. If 
you enter a value other than a 1 - 6 for the breakpoint register, the command is 
terminated immediately. Note that two values (the breakpoint register number and the 
breakpoint location) are required for this command. You must end both fields with a 
delimiter (e.g., type “B”, then “1”, then SPACE, then “A000”, and then press RETURN). 
Remember, DDT treats all delimiters (space, comma, and RETURN) identically. When 
a breakpoint is set, that location should show up in the breakpoint register display. 
Physically, a “0” for the BRK instruction is stored in memory at the requested location. 
If an Examine command is issued to look at that part of memory, a“O” will be seen, even 
though the proper mnemonic is shown in the disassembly. If a breakpoint is set at an 
examined location, the mnemonic displays in inverse video. If a breakpoint register is 
already in use when a new breakpoint is requested, the instruction at the old 
breakpoint is first restored. 


To clear a breakpoint register and restore the source code, type any delimiter after 
selecting the desired breakpoint register (e.g., type “B”, then “1”, then comma, and then 
comma to clear breakpoint 1 and restore the source code). Trying to clear a breakpoint 
that is not set will not harm anything. Note, however, that trying to set a breakpoint in 
ROM, in hardware registers, or in non-existent RAM may do some interesting things, 
but probably not what you wanted. 
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Register R <PC, 


A, P, X, Y, S>, <val > 


Use the Register command to modify the contents of any of the 6502's registers. After 
you type “R”, DDT accepts only a “P”, “A”, “X”, “Y”, or “S”. Any other character results in 
DDTs terminating the command. If you type an “A”, “X”, “Y”, or “S”, DDT allows no 
character other than DELETE until you type a delimiter. If you type a “P”, DDT allows 
an additional “C’” to indicate the Program Counter. “P” by itself indicates the Processor 
Status register. “A”, “P”, “X”,“Y”, and “S” will accept only two hex digits (i.e., one byte), 
while “PC” will accept four digits. Note that this command requires two separate values 
and two separate delimiters. 


Warning. Indiscriminate use of this command, particularly with “P”, “PC” and “S” can 
really mess things up. 


Deposit D <hstring > 


Use the Deposit command to place a string of bytes in memory. You may enter a string 
of hexadecimal values up to 10 characters (5 hex bytes). The values entered will be 
placed in successive locations, starting at the current position indicated in the display 
window and replacing whatever was there. The input string is decoded two characters 
per hex byte at a time. If an odd character is left at the end, DDT will interpret it as the 
low order nibble of a hex value. For example, entering a string of O1AABO results in 
three bytes (01, AA, and BO) being placed in memory. However, entering 01AAB 
results in 01, AA, and OB being deposited. Note that depositing a byte or a series of 
bytes doesn’t move the display window; you do this with the Examine or the Push or 
Pull window commands. 


Pull window down>down-arrow 


Use the Pull window command to pull the display window down. Depending on the 
display filter in place, this command pulls the window down by one byte (hex filter) or 
by one full instruction (disassembly filter). Because the autorepeat on the keyboard is 
active, continuing to press the down-arrow key (pressing the CTRL key isn’t 
necessary) continues to pull the window down. 


If you hold down the SHIFT key while typing the down-arrow character, the screen is 
pulled down a full screen each time. 


Push window up->up-arrow 
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Use the Push window command to push the display window up. Depending on the 
display filter in place, this command pushes the window up by one byte (hex filter) or 
by one full instruction (disassembly filter). Because the autorepeat on the keyboard is 
active, continuing to press the up-arrow key (pressing the CTRL key isn’t necessary) 
continues to push the window up. 


If you hold down the SHIFT key while typing the up-arrow character, the screen is 
pushed up a full screen. 


A problem occurs, however, when you arbitrarily examine an area of memory with the 
disassembly filter in. If you try to push the window up, there isn’t enough information 
to be able to tell if the preceding instruction was one, two, or three bytes long. DDT 
keeps track of how many bytes the window is moved each time you pull the window 
down. Thus, you can push the window back up if you have previously pulled it down 
past an instruction or group of instructions. Refer to the section in the appendix titled 
“Display window movement” for information on this feature. 


Interpretive mode I 


Window W 


Use the Interpretive mode command to place the system in an automatic single step 
mode. After each instruction is interpreted, the screen display is updated if the DDT 
screen is turned on. The display window is automatically placed in the disassembly 
mode. Pressing the BREAK key halts the interpretive mode. It’s possible to run ROM 
programs, such as BASIC, interpretively, but problems with the display can arise in 
trying to run portions of the operating system interpretively. The TRAP register is used 
for setting up the equivalent of a breakpoint in this mode. Interpretive mode runs much 
faster if the user screen is selected instead of the DDT screen because DDT doesn't 
have to update its screen if it isn’t active. 


Use the Window command to change the “filter” over the display window. “W” toggles 
between the filters. Three filters are available, an opaque filter with DDT operating 
instructions printed on it, a disassembly filter, and a hexadecimal filter. 


Trap T <1-2> , <addr> 


Use the Trap command to set one of the trap breakpoints to a specific location. The 
address entered should show up in the proper TRAP register. Trap works only in 
interpretive mode. To clear the trap, type “T”, a “1” or “2” for the TRAP register you want 
to clear and then type any two delimiters. A 0000 should show up in the register. 


Search S <hstring > 


Use the Search command to locate a specific sequence of hex characters in memory. 
You may enter a hex string up to 10 characters (5 bytes). DDT searches memory from 
the current position indicated in the display window, up through memory, and to 
location C000. Since this represents memory address space that is unavailable in the 
system, DDT attempts no search match in this area. You can still look through the OS 
ROM by examining F111, for example, and then starting the search. Memory from 
F111 to FFFF will first be searched, and then 0000 to C000. If the search is successful, 
the display window is repositioned. If it is unsuccessful, the command window is 
simply cleared for the next command. 
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DDT entry points 


Flash entry 


Warm entry 
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You can enter DDT in are three ways: 


FLASH ENTRY 
WARM ENTRY 
BREAKPOINT ENTRY 


This entry point allows immediate entry to DDT regardless of other circumstances. 
This is a single keyboard specia! character, and is initially set up as [CTRL] [SHIFT] 
[ESC] (i.e., pressing the CTRL, the SHIFT and the ESC keys at the same time). When 
DDTis initialized, the operating system code that looks at the keyboard is modified so 
that it looks for the special character first before handling normal keyboard input. If 
this character is found, DDT is entered immediately, through the flash entry point. 


The “C” command, or pressing the START key passes control to wherever the 
processor was when the DDT special character was typed. For more information on 
the flash entry mechanism, see the “Keyboard scanner” section in the appendix. 


Warning. Never use the flash entry twice to get to DDT without first exiting DDT. Doing 
so would make it impossible to return to the original calling point. 


When you use the flash entry, you will notice that the current position indicated is ata 
code sequence as follows : 


PLA 
TAX 
PLA 
TAY 
PLA 
RTI 


This is a portion of the DDT code that simulates a breakpoint to enter DDT. To get to 
the actual machine code instruction that would next be executed, do six single steps. 


This entry point is the starting point for the DDT code. The first three bytes are a JMP 
DDT ENTRY instruction. If this location is called via a JSR instruction, then the START 
key exit passes control to the calling point. This lets you call DDT at various program 
locations for setting up breakpoints, changing values, and so on. 


Example 


-- your code -- 


PHA ;this doesn’t mean anything, only an example 
JSR DDT 
-- Pressing START will return here -- 


instruction. As with the flash entry, this is actually a portion of DDT used to implement 
the entry mechanism. Single step once to get to the application code that would next 
be executed. 


When you use the warm entry, the current position will be pointing to an RTS 


Breakpoint entry 


Breakpoint entries are the most common way to enter DDT. The breakpoints first have 
to be set up via a flash or warm entry to DDT. After they are set, DDT is called if those 
specific instructions are executed. Exits from DDT breakpoints return to the code 
sequence where the breakpoint was located. Notice that the breakpoints remain in 
place unless they’re explicitly cleared. This is true even if a breakpoint has been 
tripped. 


Recall also that if the TRAP register is set in interpretive mode, then attempting to 
execute the instruction at that address halts the interpretive mode. Thus, to move past 
a trap breakpoint in interpretive mode, you have to either clear the trap or single step 
past the instruction that was trapped and then enter interpretive mode. 


How to use DDT 


The examples 


DDT contains several program examples of how to set up DDT in different ways. Turn 
" on your computer and play with DDT as you read along. 


Loading DDT into computer memory 


1. Insert the ATARI BASIC Language Cartridge into the cartridge slot of your 
computer. 


2. Have your computer turned OFF. 
3. Turn on your disk drive. 


4. When the BUSY light goes out, open the disk drive door and insert the DDT 
diskette with the label in the lower right-hand corner nearest to you. (Use disk 
drive 1 if you have more than one drive.) 


5. | Turn on your computer and your TV set. The program will load into computer 
memory and display the READY prompt of ATARI BASIC. 


So far everything seems normal, right? You might even want to type in a short 
program, such as: 


10 FOR I=0 TO 1000 
20 PRINT “I-31 

30) NEXTI 

40 GOTO 10 


% Type RUN and start the program. Now then, press the CTRL key, the SHIFT key and 
the ESC key at the same time. Eh voila! Weicome to Dunion’s Debugging Tool, better 
known as DDT. 
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There are several assembly language program “shells” you should look at. This 
requires that you use the ATARI Program-Text Editor (MEDIT). The basic idea behind 
the shell concept is to leave the actual source code modules (DDT.MAC, 
DDTLST.MAC, and the source code module you’re debugging) as undisturbed as 
possible. With a shell, you can make most necessary changes (re-orging, and so on) in 
the shell program and not change the other files. Each of these shells is described in 
the next section. 


Attaching your program to DDT 
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The assembly language program named SHELL.MAC is the general program you 
should use in assembling your program with DDT. A printout of this program is 
included in the appendix. Take a look at this printout. AS you can see, the SHELL 
program is itself a step-by-step guide to attaching DDT to your program. Let’s say you 
have a program you normally assemble using the MACRO Assembler via a source line 
command of: 


D:YOURPROG.MAC S=D:SYSTEXT.MAC 


The general procedure you would follow would be to load SHELL.MAC with MEDIT, 
edit it by following the instructions in SHELL.MAC, save the file, and assemble it witha 
source line of: 


D:SHELL.MAC S=D:SYSTEXT.MAC. 


This will produce an object file called SHELL.OB4J, which in general can be renamed 
as an AUTORUN:SYS file that loads automatically when you turn your computer on. 


Several other shell programs illustrate how to customize this process. Each of the 
shell programs describes how it has been customized. To see how any of these 
versions works, rename the desired object code file as AUTORUN.SYS and reboot the 
system (e.g., rename SHELL1.0BJ as AUTORUN.SYS). Unfortunately, due to space 
constraints, | wasn’t able to leave object code modules for each of the shells. 
SHELL2.OBJ exists as the current AUTORUN.SYS file, and SHELL3.OBJ isn’t there at 
all. To produce this file, you would need to assemble SHELL3.MAC. 


SHELL1.MAC is a stand-alone version designed primarily to let you experiment with 
DDT. The variables in the minisymbol table are some of those the operating system 
uses in controlling the system. This version of DDT can be helpful in understanding 
some of the graphics and other features of the system. You can easily examine and 
change the screen memory, display lists, shadow registers, and so on. You might even 
place a small machine-language program in memory by using the Deposit command. 


You should note a couple of things about this version. First, if you use the START key 
to exit DDT, or the “C” command, then the DUP.SYS file is toaded, overlaying DDT. 
After this happens, you must reload DDT to re-enter it. 


Second, since the WARMSTART mechanism is used to enter DDT, you should not use 
the flash entry to re-enter DDT. Doing so makes it impossible to get to DUP.SYS via 
the normal exits. 


SHELL2.MAC is a version that lets you examine the inner workings of a BASIC 
program. Notice that the variables defined in the minisymbol table are the ones BASIC 
uses to manage memory. One interesting thing you can do is to start a BASIC 
language program running, press CTRL-SHIFT-ESC to get to DDT, press SELECT to 
see the BASIC screen, and then press the letter | to run the BASIC program 
interpretively. This effectively slows BASIC down by a factor of a hundred orso. Thus, 
you can let the BASIC program run until it reaches a spot you're interested in, and then 
press BREAK to stop the interpretive mode and return to the DDT screen. Then, use 
DDT to examine exactly what BASIC is doing internally. 


SHELL3.MAC is a version designed for testing an assembly language subroutine. A 
routine on the diskette called PSEUDO.MAC is an implementation of a pseudo 
random number generator. Essentially, this routine generates a pseudo random 
number less than or equal to a variable “upper limit.” For more information on how this 
subroutine works, look at the source code using MEDIT. After assembling SHELL3.MAC, 
rename the object file, SHELL3.OBJ, as AUTORUN.SYS. Then, rebooting the system 
will load DDT and PSEUDO, initialize DDT, and then do a JSR DDT for initial 
breakpoint setting, and so on. 


With this version, you should start to get an idea of the power of DDT. First, if you're 
testing a subroutine dealing with numerical values (as does PSEUDO), then you 
needn’t set up an involved printing routine to check the output of the routine. It’s very 
simple to place the result in a location and set up that location as an entry in the 
minisymbo! table. 


Next, notice how the minisymbol table can be useful in several ways. You can use a 
symbol to monitor a routine’s output (e.g., VALUE), input parameters (e.g., UPPER & 
DEGRAN), and even small areas of memory (e.g., RANNUM + RANNUM2 = 4 
contiguous bytes). However, you can just as easily define the symbols as locations 
(i.e., labels) in your source code. Their value on the screen will probably be 
meaningless, but the disassembly listing becomes much more readable. You can even 
waste a variable calling it “...... ” to separate symbol variables from symbol labels. 


To get an idea of how to use DDT, copy SHELL3.OBJ as AUTORUN.SYS, remove any 
cartridge and reboot your system. It should come up directly into DDT. Type “W” to 
toggie the screen, then press the OPTION key twice to single step to the start of the 
driver code for PSEUDO. Set a breakpoint at the location where there is aJMP LOOP 
instruction (you can look for this location by pulling the display window down; it 
should be at $4018). Now press the START key. The screen should flash and DDT 
should return with the PC set at $4018. Continue to do this. Note each time that the 
contents of VALUE are less than or equal to UPPER. Now experiment. Set the TRAP to 
$4018, then run interpretively, and so on. 


SHELL4.MAC is a version designed for debugging a hybrid program (i.e., part BASIC, 
part assembly language). The object code here consists of the pseudo random 
number generator routine, the link to BASIC, and DDT. To use this version, rename 
SHELL4.0BJ as AUTORUN.SYS and reboot the system. When you see the READY 
prompt, type RUN ‘D:PSEUDO’ , and press the RETURN key. 
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In the BASIC program PSEUDO, you can reset the “seed” or starting point for the 
pseudo random number generator. Try setting the seed to some value, and entering 
values for the upper limit and number of values to generate. Note the pseudo random 
numbers generated. Now go back and reset the seed to the same value you chose 
earlier. Also pick the same values you had selected for upper limit and pseudo random 
numbers to generate. You should get the same list of numbers. This is, of course, the 
power of a pseudo random number generator—the ability to generate numbers 
repeatedly that appear to be random. 


Interactions with DOS 
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If you decide to set the origin of DDT to sit right on top of the FMS portion of DDT, be 
aware that this is exactly where DUP.SYS loads. Thus, if you try to load DUP.SYS 
(using the DOS command from BASIC, for example), it will overlay DDT. No real 
problems will ensue from this operation, but you might run into some difficulty in 
trying to reload DDT from DOS. For instance, you must have created a MEM.SAV file 
before the operating system will let you overlay DUP.SYS. In general, if you need to 
use DUP.SYS , then you should ORG DDT beyond where DUP.SYS will load. 


You can call DOS from DDT in several ways. One simple way is to have an instruction 
in your code like: 


DOSCALL JMP (DOSVEC) ;DOSVEC = SOA 


Then, to call DOS, use a DDT “G” command with the address of DOSCALL. 
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Keyboard scanner 


During DDT initialization, the system keyboard vector is redirected to a preprocessor, 
which checks for the DDT flash entry special character. If this character is seen, 
control passes to the flash entry point; otherwise, control passes to the normal 
keyboard processing routine. 


When writing applications, you need to understand a couple of things about this 
preprocessor feature. 


1. Keyboard interrupts must be enabled. 


2. The character watched for is stored in an internal table and may be changed. 
In the source code, the table location is DBCHR, which is initially set to $DC. 


Single stepping 


DDT is equipped with a single step mechanism for detailed examination of code 
execution. This is invoked by pressing the OPTION key or via the “I” command. The “I” 
command activates a single step automatic mode, which is terminated by pressing the 
BREAK key. 


When a single step request is issued, an examination is made of the instruction 
pointed to by the PC register. If it is not a “forbidden” instruction (i.e., one that could 
mess up DDT), it is transferred to a test bed, the 6502 registers are loaded from the 
register shadows, and then the instruction is executed directly. After execution, the 
register state is saved, the screen display is updated, and control returns to DDT. 


lf DDT cannot allow the instruction to be executed directly (e.g., a JMP instruction), 
then the instruction is simulated and the saved register state and display are properly 
updated before control is returned to DDT. Forbidden instructions include all branch 
instructions, JMP, Jump indirect, JSR, RTI, RTS and BRK. 


If a breakpoint is encountered during single stepping, DDT gets the actual instruction 
that should be at that location before executing it. If, for some reason, the BRK 
instruction you are single stepping past does not correspond to one of DDT’s 
breakpoints, an NOP is loaded instead. This is also the case if the instruction is 
undefined. 


The branch instructions are handled in a hybrid manner. The actual branch 
instruction is placed in a test bed, as shown below. Thus, after execution of the branch 
instruction, DDT can infer where the branch instruction with the real offset would have 
gone. This value is used to update the resultant address that will be placed in the PC. 
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Branch 


Conditional ¢ 
Instruction 


DDT-s use of system resources 


The DDT code itself occupies about 6K of RAM, and the display screen another 1K. 
Extreme care has been taken to ensure that DDT runs parallel to normal system 
functioning. In interpretive mode, for example, you should be able to use all the 
system’s features (including the keyboard and the function keys), except for the 
BREAK key, which DDT reserves for itself. One underlying assumption in DDT is that 
your program is going to be generally operating according to the protocols 
established by the existing operating systems. There are six page zero locations that 
DDT uses when active, 2-7. The operating system will not be using these during the 
time DDT is active. In the event that your program uses these locations (naughty! 
naughty!), they are saved upon entering DDT and restored upon exit. However, if they 
are examined while DDT is in control, they will reflect DDT values, and not your 
program’s values. 


DDT has only two global variables, DDTI and ECODE, both of which are used in 
SHELL.MAC. Otherwise, all variables are local. The shell programs themselves also 
use global variables DDT and ICODE. 


Display window movement 


DDT maintains a “pull stack” while the disassembly filter is in place. This means that 
each time you pull the display window down, DDT places the number of bytes that the 
window was pulled in a stack. Thus, when you want to push the window up, DDT 
checks to see if there are any values left in the pull stack. If so, you can push the 
window up. If not, nothing happens. The pull stack is cleared whenever DDT is 
entered, or when an Examine command is typed. To conserve memory, four pull 
values (which will be a 1, 2, or 3) are packed into each byte in the stack. A total of 64 
bytes are reserved for the stack. Thus you can pull the window down 256 times before 
the stack runs out, at which time the first values in the stack are lost and you can’t back 
up as far. In computer terms, the stack is implemented as a circular buffer. 
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Things to watch out for 


To my continued dismay, a few gotchas remain in DDT. In general, these occur when 
you are single stepping or running interpretively. If the interpreted code messes 
around with the display list, or with ANTIC, or CTIA/GTIA, then you might end up with 
ascrambled DDT screen. Usually this isn’t fatal, just distracting. To restore the normal 
DDT screen, press the BREAK key to halt the interpretive mode, and then press the 
SELECT key twice. 


Trying to do I/O from disk or any other real time activity in either interpretive mode or 
single step mode is probably going to produce a mysterious occurrence. You should 
set up breakpoints so that this type of I/O is done in real time, and then call DDT. 


Be wary of using the flash entry point (entered by pressing CTRL-SHIFT-ESC) to 
re-enter DDT after it has been entered (but not exited). This will definitely confuse the 
system. 


Some programs that you want to debug may turn out to be too big to assemble along 
with DDT. If this occurs, AMAC will simply lock up and die. You can handle this by 
assembling one shell containing DDT and another containing the test program. True, 
you will have to do alittle planning to make sure the ORG values are correct, and that 
the test code knows where DDT (and consequently the minisymbol table) and the 
initialization code are located. But this isn’t difficult to do once you've played around 
with DDT for awhile. After you’ve produced the two object code modules, rename the 
one containing DDT as AUTORUN.SYS. Then copy the other to AUTORUN.SYS with 
the append option. DUP.SYS will tack your test code to the end of the DDT code. Don’t 
worry about the fact that the segments of code may be ORGed at different areas. The 
system binary loader will handle the segments properly. All you have to do is be sure 
the proper minisymboi table is loaded last, and the last segment has the proper 
initialization address loaded into the RUN vector. 


Finally, going back and forth between DDT and DUP.SYS (if they overlay each other) 


seems to introduce unknown things into the system. If this happens, try pressing 
SYSTEM RESET first, and if this fails, simply reboot the system. 
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HK HEI He KKK IRI II III KEENE ERE IK EKER IK HEE IRE I REIT HERE IK IRE IEE ERE EERE 


THIS IS THE GENERAL SHELL PROGRAM 


YOU SHOULD ASSEMBLE THIS PROGRAM 
TO ATTACH YOUR TEST PROGRAM 
TO THE DEBUGGING SYSTEM. 


. REFER TO THE DDT DOCUMENTATION 

5 FOR INSTRUCTIONS ON CUSTOMIZING 

% THIS PROGRAM FOR YOUR PARTICULAR 
i NEEDS. 


IK HH IK KK II IK RII HRITHIK KKK IIIT TIF KTR IIT FTIR TTI IKK THI KK TKK IRIN I AH III ITH TK ERIK KEI IKEA 
* 
* 


* 


* 


STEP 1 


* 


* 


FIRST YOU HAVE TO DECIDE WHERE 
DDT AND YOUR CODE WILL RESIDE. 


ONE CHOICE IS TO LET DDT SIT 
RIGHT ON TOP OF DOS, AND IN A 
SENSE, BE AN EXTENSION OF IT. 


IN THIS CASE THE ORG STATEMENT 
SETS DDT TO BEGIN RIGHT WHERE 
DOS STOPS. NOTE THIS IS THE 
STANDARD 2 DISK DRIVE DOS 
CONFIGURATION. 


+ * * ee FF HF HF HF HH 


- IF YOU HAVE SPECIAL CONDITIONS 
. (FEWER DISK DRIVE BUFFERS, THE 
850 ON, ...) THEN CHANGE THE 
: ORG TO SUIT YOUR TASTE. 

ORG $1CFC 
STEP 2 


NOW YOU HAVE TO MAKE SURE THE 
DDT CODE IS ASSEMBLED. 

HERE, IT 1S ASSUMED THAT ALL 

THE NECESSARY FILES ARE LOCATED 
ON DRIVE 1. 


+ *£ * * & & FH 


YOU CAN CHANGE THE FILE 
DESIGNATORS HOWEVER, TO FIT 
YOUR DEVELOPMENT SYSTEM. 


+ * & 


PROC 
DDT = bs 
INCLUDE D:DDT.MAC 


22 Appendix - Technical details 


He Hee HK HK IR RIK He HK RIT TI RHEIN IK IT KERR EEE IERIE HEI ERR EIA KR EERE IIHR 


+ + * ee HH HF HH HH 


+ * * * * * &£ F & HF F 


STEP 3 


THE NEXT FILE IS THE DISPLAY LIST 
AND SCREEN AREA FOR DDT. 


THIS CODE TAKES UP JUST UNDER 1 K 
OF MEMORY SPACE, AND HAS SOME 
BOUNDARY CROSSING RESTRICTIONS. 


NOTE THAT THE FOLLOWING ORG 
STATEMENT ASSURES THAT THE DISPLAY 
LIST DOES NOT CROSS A 1K BOUNDARY 
AND THAT THE SCREEN MEMORY DOES 
NOT CROSS A 4K BOUNDARY. 


IF YOU WANT TO MOVE THE SCREEN 
FOR ANY REASON, MODIFY THIS 
STATEMENT. 


NOTE ALSO THAT THE ICODE LABEL 
IS USED TO DEFINE A SPOT TO 
STORE INITIALIZATION CODE. 

9 BYTES ARE SAVED FOR THIS 


IF ((((( HIGH *)/4H 1)*1024}*) < 33) OR [(((( HIGH *)/8+ 1)*1024-*) 
ORG ([((HIGH *)/4# 1)*1024 
ENDIF 


INCLUDE D:DDTLST.MAC 
EPROC 


ICODE =* 


* 


ORG *+9 


He Fee He He He HH He te HH He HK He HH HTK IH KIKI RT IIIT RIT ICH TIKIT TIER I KIKI THVT STII IT KE III EIR IKE RENEE AII AI KI 


* 


* 


* * * & &* ©  * © HF & HH 


STEP 4 


THE DDT INITIALIZATION CODE SETS 

UP A ROUTINE THAT MODIFIES THE 
MEMLO POINTER WHENEVER THE RESET 
BUTTON IS PRESSED. 


NORMALLY THIS IS USED TO “HIDE” 
THE DDT CODE, AND MAKE THE FREE 
MEMORY AREA START JUST AFTER DDT 


TO MODIFY THIS SET UP YOU WILL 
HAVE TO DEFINE AN ECODE VALUE TO 
BE PLACED IN THE MEMLO POINTER. 


ONE SUGGESTION WOULD BE TO SIMPLY 
PUT THE NORMAL VALUE THAT WOULD 
BE THERE ANYWAY. 


FOR INSTANCE IN THE STANDARD DOS 


CONFIGURATION, YOU MIGHT PUT 
ECODE = SICFC 
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STEP 5 


NOW YOU HAVE TO ATTACH YOUR OWN 
CODE. A COUPLE OF THINGS SHOULD 
BE NOTED. 


+ + + & & FF HH % HH 


1. YOU SHOULD REMOVE ANY ORG 
STATEMENTS FROM YOUR CODE 
AND PLACE THEM HERE. 

WITH NO NEW ORG STATEMENT, 
YOUR CODE WILL FOLLOW THE 
DDT CODE. CURRENTLY THAT 
MEANS YOUR CODE WOULD START 
AROUND $3715 


2. REMOVE ANY END STATEMENT FROM 
YOUR PROGRAM. IF NOT, IT WILL 
DEFINITELY SCREW THINGS UP. 


+ + ££ & F & & FF F HF 


* 


ORG YOURORG 
INCLUDE D:YOURPROG 


* 


We Ve He He ie He HH IH HICK KH III IH ITT HRI IIR IIIS IIIT THAIS STIR IH IRI ETI ERITH IKE ERIK EERE 


STEP 6 


IF YOU WANT TO DEFINE A MINI 
SYMBOL TABLE, THIS IS THE SPOT. 

THE ORG STATEMENT SHOULD SET THE 
ORG TO WHEREVER DDT IS+3 


* * & *  € & Fe  H FF 


RECALL THAT EACH SYMBOL NEEDS TO 
BE DEFINED LIKE: 


* 


+ 


* DB ‘SYMBOL’ = ;}6 CHARACTERS 
J DW SYMBOL 3SYMBOL LOCATION 
i DB 1 3A 1 OR 2 

ORG DDT+3 

DB " ‘ 

DW oO 

DB 1 
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* 


* 
* 
* 


STEP 7 
2 NOW YOU HAVE TO TELL THE SYSTEM 
: WHERE TO GO TO RUN THE CODE 


THE STRUCTURE WE HAVE HERE WILL 
INITIALIZE DDT, CALL DDT TO 

ALLOW YOU TO SET UP INITIAL 
BREAKPOINTS, AND THEN JUMP TO 
THE START OF YOUR CODE. 


+ * & ee ee 


ORG ICODE 

JSR DDTI AINITIALIZE DDT 

JSR DDT sENTER DDT 

JMP YOURORG ;AND RUN YOUR CODE 


END ICODE 


PEP PrP Por PPP rere rr re errr errr rte rrr rrr errr rrr rTP rrr reer rrr errr Ty 
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ATARI" 
PROGRAM 
Oe EXCHANGE 
P.O. Box 3705 


Santa Clara, CA 95055 


y 


We're interested in your experiences with APX programs 
and documentation, both favorable and unfavorable. 
Many of our authors are eager to improve their programs 
if they know what you want. And, of course, we want to 
know about any bugs that slipped by us, so that the 
author can fix them. We also want to know whether our 


1. Name and APX number of program. 


Review Form 


instructions are meeting your needs. You are our best 
source for suggesting improvements! Please help us by 
taking amomentto fillin this review sheet. Fold the sheet 
in thirds and seal it so that the address on the bottom of 
the back becomes the envelope front. Thank you for 
helping us! 


2. If you have problems using the program, please describe them here. 


3. What do you especially like about this program? 


4. What do you think the program’s weaknesses are? 


5. How can the catalog description be more accurate or comprehensive? 


6. Onascale of 1 to 10, 1 being “poor” and 10 being “excellent”, please rate the following aspects of this program: 


Easy to use 


User-oriented (e.g., menus, prompts, clear language) 


Enjoyable 

Self-instructive 

Useful (non-game programs) 
Imaginative graphics and sound 


7. Describe any technical errors you found in the user instructions (please give page numbers). 


8. What did you especially like about the user instructions? 


9. What revisions or additions would improve these instructions? 


10. On a scale of 1 to 10, 1 representing “poor’ and 10 representing “excellent”, how would you rate the user 
instructions and why? 


11. Other comments about the program or user instructions: 


From 


STAMP 


ATARI Program Exchange 
P.O. Box 3705 
Santa Clara, CA 95055 


[seal here] 


DUNION’S DEBUGGING TOOL (DDT) 
by Jim Dunion 


Recommended for assembly language programmers/ 
Written in machine language 


e A flexible, extensive source language debugging tool 


¢ Information-packed display lets you easily monitor and change 
the internal state of the machine 


¢ Display includes 6502 registers, memory address space, system 
stack, user-defined symbol table, and breakpoint registers 


e Your program’s screen display remains intact while using DDT 
© Sample programs illustrate ways to set up and use DDT 


The features designed into the ATARI Home Computer make it 
unique among current microcomputers. However, getting at some 
of these features is done more efficiently in low-level assembly 
language programming than in high-level languages like BASIC 
and PILOT, Assembly language programmers can benefit greatly 
from adequate development tools. The ATARI MACRO Assembler 
and Program-Text Editor™ is one such powerful programming tool, 
and now we have a companion piece, Dunion’s Debugging Tool 
(DDT), which is a debugging tool specifically designed for use with 
the MACRO Assembler. 


Most of the time, correcting a program bug isn’t the central problem; 
finding it is. That's where DDT comes in. DDT operation centers 
around control of its display screen and around the ability to 
monitor and change easily the internal state of the machine. This 
feature works while also maintaining the user’s screen display. The 
display is divided into six areas, each showing a different aspect of 
what’s going on inside the computer at any instant. The areas are: 
(1) a register display showing the current contents of the 6502 
processor registers; (2) a display window forming a window into the 


JIM DUNION 


About the author 


When Jim Dunion, of Sunnyvale, Cali- 
fornia, was workng on a programming 
project for the ATARI Summer Camps, 
he was using the ATARI MACRO Assem- 
bler. Because he was frustrated by the 
lack of adebugging utility for the assem- 
bler, he wrote his own, DDT. Its popu- 
larity shows how helpful DDT has been 
to other programmers since then. As a member of Atari’s Corporate 
Research staff, Jim asks the questions that are on the frontiers of the 
computer world. He doesn’t concentrate on problems that can be 
solved right away; he prefers to take a long-range view in his 
research. He's studying artificial intelligence, in particular asking 
what it takes for a computer system to create humor. The question is 
expecially challenging, Jim points out, because humor is a matter of 
style, which appeals to each person in a different way. Jim has 
shared his interest in the merging of psychology and technology 
with groups outside the industry, including Esalen, where he’s been 
a consultant. 


ATARI® 
PROGRAM 
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P.O, Box 3705 
Santa Clara, CA 95055 


system memory address space; (3) a stack display showing the top 
fifteen items on the system stack; (4) a mini-symbol table showing 
the names and values of fifteen user-defined declared symbols; (5) a 
breakpoint table showing the settings of user-definable breakpoint 
and trap registers; and (6) acommand window showing commands 
typed from the keyboard. Commands are available for changing the 
contents of registers and memory, examining areas of memory, and 
single-stepping the processor. You can assemble DDT along with 
your source code if you wish, and you can place DDT in memory 
according to what you want to work on. Example programs included 
in the package illustrate ways to set up and use DDT’s many 
features. 


The author invites written questions and comments. 


REVIEW COMMENTS 


For all levels of assembly language programmers, DDT is definitely 
worth learning to use. 


The user manual is very good. 


Diskette: version 1 


Edition B 


Limited Warranty on Media and Hardware Accessories. Atari, Inc. ("Atari") 
warrants to the original consumer purchaser that the media on which APX 
Computer Programs are recorded and any hardware accessories sold by APX 
shall be free from defects in material or workmanship for a period of thirty (30) 
days from the date of purchase. If you discover such a defect within the 30-day 
period, call APX for areturn authorization number, and then return the product 
to APX along with proof of purchase date. We will repair or replace the product 
at our option. If you ship an APX product for in-warranty service, we suggest 
you package it securely with the problem indicated in writing and insure it for 
value, as Atari assumes no liability for loss or damage incurred during 
shipment. 


This warranty shall not apply if the APX product has been damaged by 
accident, unreasonable use, use with any non-ATARI products, unauthorized 
service, or by other causes unrelated to defective materials or workmanship. 


Any applicable implied warranties, including warranties of merchantability 
and fitness for a particular purpose, are also limited to thirty (30) days from the 
date of purchase. Consequential or incidental damages resulting from a 
breach of any applicable express or implied warranties are hereby excluded. 


The provisions of the foregoing warranty are valid in the U.S. only. This 
warranty gives you specific legal rights and you may also have other rights 
which vary from state to state. Some states do not allow limitations on how long 
an implied warranty lasts, and/or do not allow the exclusion of incidental or 
consequential damages, so the above limitations and exclusions may not apply 
to you. 


Disclaimer of Warranty on APX Computer Programs. Most APX Computer 
Programs have been written by people not employed by Atari. The programs 
we select for APX offer something of value that we want to make available to 
ATARI Home Computer owners. In order to economically offer these programs 
to the widest number of people, APX Computer Programs are not rigorously 
tested by Atari and are sold on an “as is” basis without warranty of any kind. 
Any statements concerning the capabilities or utility of APX Computer 
Programs are not to be construed as express or implied warranties. 


Atari shall have no liability or responsibility to the original consumer pur- 
chaser or any other person or entity with respect to any claim, loss, liability, or 
damage caused or alleged to be caused directly or indirectly by APX Computer 
Programs. This disclaimer includes, but is not limited to, any interruption of 
services, loss of business or anticipatory profits, and/or incidental or conse- 
quential damages resulting from the purchase, use, or operation of APX 
Computer Programs. 


Some states do not allow the limitation or exclusion of implied warranties or 
of incidental or consequential damages, so the above limitations or exclusions 
concerning APX Computer Programs may not apply to you. 


For the complete list of current 
APX programs, ask your ATARI retailer 
for the APX Product Catalog 


